home *** CD-ROM | disk | FTP | other *** search
/ NeXT Education Software Sampler 1992 Fall / NeXT Education Software Sampler 1992 Fall.iso / Programming / Classes / SocketClasses / doc / ascii / SktSocketManager.spec < prev    next >
Encoding:
Text File  |  1992-03-28  |  14.1 KB  |  490 lines
  1. Copyright 1992 by Nik A Gervae.  This is part of the documentation for
  2. the socket classes, which are licensed under the terms of the GNU General
  3. Public License as published by the Free Software Foundation.
  4.  
  5. The documented program and this documentation are distributed in the hope
  6. that it will be useful, but are provided "AS IS" AND WITHOUT ANY WARRANTY;
  7. without any express or implied warranty of MERCHANTABILITY or FITNESS FOR
  8. A PARTICULAR PURPOSE. See the GNU General Public License for more details.
  9. Any use or distribution of the program and documentation must include
  10. appropriate copyrights to acknowledge Nik A. Gervae and the Free Software
  11. Foundation, Inc.
  12.  
  13. You should have received a copy of the GNU General Public License
  14. along with this documentation; if not, write to the Free Software
  15. Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  16.  
  17. ===============
  18.  
  19. SktSocketManager
  20.  
  21. INHERITS FROM    Object
  22.  
  23. DECLARED IN    SktSocketManager.h
  24.  
  25.  
  26.  
  27. CLASS DESCRIPTION
  28.  
  29. The SktSocketManager class, together with the SktSocket and 
  30. SktSocketUser classes, provides an application with the ability to act as a 
  31. server for Berkeley UNIX stream socket connections.  An SktSocket 
  32. object handles input/output on the socket itself, while an instance of a 
  33. subclass of SktSocketUser processes the input and provides output to the 
  34. SktSocket.  The SktSocketManager class coordinates the efforts of each 
  35. SktSocket.
  36.  
  37. SktSocketManager requires an update message to act. The update 
  38. message is best sent as a regular interval message, from within a timed 
  39. entry, or within a loop.
  40.  
  41. During an update cycle, an SktSocketManager has all SktSocket objects 
  42. perform input and output, and handles requests for connections by 
  43. creating a new SktSocket/SktSocketUser pair.
  44.  
  45. The update method makes use of the select() UNIX system call to 
  46. determine if there's any data waiting to be read or written.  Several 
  47. methods have been provided to allow precise control over the behavior of 
  48. this function, but you don't need to know about select()  to get started 
  49. using the socket classes.
  50.  
  51. These classes are intended to make sockets easy to use.  However, several 
  52. methods have been provided to access fairly low-level details of sockets 
  53. which may be useful in some situations.  For more information on 
  54. sockets, see: the related UNIX man pages; “An Introductory 4.3BSD 
  55. Interprocess Communication Tutorial” (reprinted in UNIX Programmer's 
  56. Supplementary Documents Volume 1, PS1:7); or, “An Advanced 4.3BSD 
  57. Interprocess Communication Tutorial” (reprinted in UNIX Programmer's 
  58. Supplementary Documents Volume 1, PS1:8).
  59.  
  60. See also: SktSocket, SktSocketUser
  61.  
  62.  
  63.  
  64. INSTANCE VARIABLES
  65.  
  66. Inherited from Object    Class        isa;
  67.  
  68. Declared in SktSocketManager
  69.             FILE        *logfile;
  70.             id        userClass;
  71.             char        *hostaddress;
  72.             char         *hostname;
  73.             int        servicePort;
  74.             int        numAvailFds;
  75.             int        maxSocketFd;
  76.             int         serviceSocketFd;
  77.             List        *openSockets;
  78.             BOOL        doesLog;
  79.             NXZone        *zone;
  80.             struct timeval    selectTimeout;
  81.             BOOL        timeoutIndefinite;
  82.             int        selectSignalMask;
  83.  
  84. logfile     The file to which all diagnostic output is 
  85.         printed.
  86.  
  87. userClass     Factory for new SocketUsers.
  88.  
  89. hostaddr     The primary Internet address of the machine 
  90.         the SktSocketManager's application is 
  91.         running on, in dot notation.
  92.  
  93. hostname     The name of the machine the 
  94.         SktSocketManager's application is running 
  95.         on.
  96.  
  97. servicePort     The Internet port used to connect to the 
  98.         SktSocketManager's application (for 
  99.         example, via TELNET).
  100.  
  101. numAvailFds     The number of file descriptors available for 
  102.         SktSocket assignment.
  103.  
  104. maxSocketFd     The highest valued file descriptor currently 
  105.         assigned.
  106.  
  107. serviceSocketFd     The file descriptor of SktSocketManager's 
  108.             socket.
  109.  
  110. openSockets         A List of currently active SktSocket objects.
  111.  
  112. doesLog            YES if non-error messages are written to the 
  113.             log file.
  114.  
  115. zone            The zone that the SktSocketManager was 
  116.             allocated from.
  117.  
  118. selectTimeout        The longest time that the SktSocketManager 
  119.             will wait for input or output during an 
  120.             update.
  121.  
  122. timeoutIndefinite    YES if selectTimeout is ignored, and 
  123.             update will block indefinitely until there is 
  124.             input or output, or until a signal occurs.
  125.  
  126. selectSignalMask    A mask of signals that are blocked during 
  127.             the select() system call in update.
  128.  
  129.  
  130.  
  131. METHOD TYPES
  132.  
  133. Initializing and freeing a SktSocketManager
  134. - initPort:logfile:fdCapacity:
  135. userClass:
  136. - setSocketOptions:
  137. - free
  138. - setDoesLog:
  139. - doesLog
  140.  
  141. Advanced initialization (you should know about select())
  142. - setTimeoutSeconds:
  143. microseconds:
  144. - getTimeoutSeconds:
  145. microseconds:
  146. - setTimeoutIndefinite
  147. - isTimeoutIndefinite
  148. - setSignalMask:
  149. - signalMask
  150.  
  151. Accessing SktSocketManager attributes
  152. - setFdCapacity:
  153. - adjustFdCapacity:
  154. - fdCapacity
  155. - numAvailFds
  156. - logfile
  157. - hostaddress
  158. - hostname
  159. - servicePort
  160. - getInetAddresses
  161.  
  162. Synchronization and management    - update
  163. - closeSocket:
  164. - closeAllSockets
  165.  
  166. Utility methods    - announceString:
  167. - log:
  168.  
  169.  
  170.  
  171. INSTANCE METHODS
  172.  
  173.  
  174.  
  175. adjustFdCapacity:
  176. - (int)adjustFdCapacity:(int)byAmount
  177.  
  178. Adjusts the number of available file descriptors by byAmount.  If this 
  179. would result in the total number of descriptors reserved being greater 
  180. than the process's dtablesize (see getdtablesize(2) in the UNIX manual 
  181. pages), no change is made.  If it would result in less than zero descriptors 
  182. being reserved, the number of available descriptors is set to zero.  Returns 
  183. the new capacity of the SktSocketManager.
  184.  
  185. This method is useful for reserving file descriptors in your process for 
  186. things other than socket connections.
  187.  
  188.  
  189. See also: - initPort:logfile:capacity:userClass:, - fdCapacity:, 
  190. - numAvailFds, - setFdCapacity:
  191.  
  192.  
  193.  
  194. announceString:
  195. - announceString:(const char *)announcement
  196.  
  197. Has every active SktSocket queue announcement as output.  Returns self.
  198.  
  199. See also: - queueOutput: (SktSocket)
  200.  
  201.  
  202.  
  203. fdCapacity
  204. - (int)capacity
  205.  
  206. Returns the number of file descriptors, both available and in use, reserved 
  207. by the SktSocketManager.
  208.  
  209. See also: - adjustFdCapacity:, 
  210. - initPort:logfile:capacity:userClass:, - numAvailFds, 
  211. - setFdCapacity:
  212.  
  213.  
  214.  
  215. closeAllSockets
  216. - closeAllSockets
  217.  
  218. Sends self a closeSocket: message for each open SktSocket.  Returns 
  219. self.
  220.  
  221. See also: - closeSocket:
  222.  
  223.  
  224.  
  225. closeSocket:
  226. - closeSocket:socketObj
  227.  
  228. Removes socketObj from the list of open SktSockets and sends it a free 
  229. message.  Returns self.
  230.  
  231. See also: - closeAllSockets
  232.  
  233.  
  234.  
  235. doesLog:
  236. - (BOOL)doesLog
  237.  
  238. Returns YES if non-error messages (notices of new connections, closing 
  239. of connections, etc.) as well as error messages will be written to the log 
  240. file.  The default is to write such messages.
  241.  
  242. See also: - setDoesLog:
  243.  
  244.  
  245.  
  246. getInetAddresses
  247. - (char **)getInetAddresses
  248.  
  249. Returns a null-terminated array of character strings containing the 
  250. Internet addresses (in dot notation) of the machine the application is 
  251. running on.  This array is created on demand, and it and its contents may 
  252. be freed by the sender of the message when it is no longer needed (you 
  253. must free only the top-level pointer).  If the addresses can't be retrieved, 
  254. this method returns NULL.
  255.  
  256. See also: - hostaddress, - hostname
  257.  
  258.  
  259.  
  260. getTimeoutSeconds:microseconds:
  261. - getTimeoutSeconds:(long int *)secs microseconds:(long int *)usecs
  262.  
  263. Returns by reference the components of the timeout value used by 
  264. select() in update.  update will not wait longer than this for input or 
  265. output to process.  The default values for these components are 0 and 0; 
  266. that is, update will simply poll for input or output.  Returns self.
  267.  
  268. See also: - setTimeoutSeconds:microseconds:, 
  269. - setTimeoutIndefinite, - isTimeoutIndefinite, - update, select(2)
  270.  
  271.  
  272.  
  273. hostaddress
  274. - (const char *)hostaddress
  275.  
  276. Returns the Internet address of the machine the SktSocketManager's 
  277. application is running on, in dot notation.
  278.  
  279. See also: - hostname, - getInetAddresses
  280.  
  281.  
  282.  
  283. hostname
  284. - (const char *)hostname
  285.  
  286. Returns the hostname of the machine the SktSocketManager's application 
  287. is running on.
  288.  
  289. See also: - hostaddr, - inetAddresses
  290.  
  291.  
  292.  
  293. initPort:logfile:fdCapacity:userClass:
  294. - initPort:(int)portNum logfile:(FILE *)file fdCapacity:(int)cap
  295.     userClass:aClass
  296.  
  297. Attempts to create a socket bound to portNum.  This socket is used to 
  298. handle requests for new connections.  In addition, file is recorded as the 
  299. file for diagnostic output, cap file descriptors are assumed available by 
  300. the SktSocketManager for creation of new SktSocket objects and aClass 
  301. is recorded as the class object which will allocate SktSocketUser objects 
  302. for newly created Sockets.  A new SktSocketUser is created by sending 
  303. alloc and init messages to the SktSocketUser subclass represented by 
  304. aClass.
  305.  
  306. This method also invokes setSocketOptions:, so that you may set file 
  307. descriptor flags in subclasses.  If setSocketOptions: returns nil, the 
  308. initialization is cancelled and returns nil.  An SktSocketManager doesn't 
  309. set any options for itself.
  310.  
  311. Returns self if successful, or nil on any of these conditions:  portNum is 
  312. in use or reserved (ports equal to or below 1024 are reserved for use by 
  313. the super user), cap is negative or greater than the process's dtablesize 
  314. (see getdtablesize(2) in the UNIX manual pages), aClass isn't 
  315. SktSocketUser or a subclass thereof, setSocketOptions: returns nil, the 
  316. socket couldn't be bound, or the List of open SktSockets couldn't be 
  317. created.  An error message is logged detailing the particular error 
  318. condition.
  319.  
  320. This method is the designated initializer for SktSocketManager objects.
  321.  
  322. See also: - setSocketOptions:, - adjustFdCapacity:, - fdCapacity:, 
  323. - numAvailFds, - servicePort, - setFdCapacity:, fcntl(2), 
  324. setsockopt(2)
  325.  
  326.  
  327. isTimeoutIndefinite
  328. - (BOOL)isTimeoutIndefinite
  329.  
  330. Returns YES if update waits indefinitely for input or output to process.  
  331. The default behavior is to poll, and not wait at all.  Returns self.
  332.  
  333. See also: - setTimeoutIndefinite, 
  334. - setTimeoutSeconds:microseconds:, 
  335. - getTimeoutSeconds:microseconds:, - update, select(2)
  336.  
  337.  
  338.  
  339. log:
  340. - log:(const char *)format, ...
  341.  
  342. Prints message to the log file, in the same manner as fprintf().  Returns 
  343. self.
  344.  
  345.  
  346.  
  347. numAvailFds
  348. - (int)numAvailFds
  349.  
  350. Returns the number of file descriptors the SktSocketManager currently 
  351. has reserved and unassigned to sockets.
  352.  
  353. See also: - adjustCapacity:, - capacity:, 
  354. - initPort:controller:capacity:userClass:, - setCapacity:
  355.  
  356.  
  357.  
  358. servicePort
  359. - (int)servicePort
  360.  
  361. Returns the Internet port used to connect to the SktSocketManager (for 
  362. example, via TELNET).
  363.  
  364. See also: - initPort:controller:capacity:userClass:
  365.  
  366.  
  367.  
  368. setDoesLog:
  369. - setDoesLog:(BOOL)flag
  370.  
  371. If flag is YES, then non-error messages (notices of new connections, 
  372. closing of connections, etc.) as well as error messages will be written to 
  373. the log file.  The default is to write such messages.  Returns self.
  374.  
  375. See also: - doesLog
  376.  
  377.  
  378.  
  379. setFdCapacity:
  380. - setFdCapacity:(int)cap
  381.  
  382. Changes the number of file descriptors reserved by the 
  383. SktSocketManager (both currently allocated and free) to cap.  If cap is 
  384. greater than the process's dtablesize (see getdtablesize(2) in the UNIX 
  385. manual pages), no change is made.  If cap is less than zero, then zero 
  386. descriptors are reserved.  Returns self.
  387.  
  388. This method is useful for reserving file descriptors in your process for 
  389. things other than socket connections.
  390.  
  391. See also: - fdCapacity:, - adjustFdCapacity:, 
  392. - initPort:logfile:fdCapacity:userClass:, - numAvailFds
  393.  
  394.  
  395.  
  396. setSignalMask:
  397. - setSignalMask:(int)mask
  398.  
  399. Records mask as the signal mask to use before a call to select(), so that 
  400. select() isn't affected by the signals specified in mask.  Returns self.
  401.  
  402. To create a signal mask, use the marco signalMask(), defined in 
  403. <signal.h>.  For example, to get the signal mask for SIGHUP and 
  404. SIGINT, write
  405.  
  406. int mask = signalMask(SIGHUP) || signalMask(SIGINT);
  407.  
  408. You can build up a mask covering many signals by logically combining 
  409. these mask values.
  410.  
  411. See also: - signalMask, - update, sigsetmask(2)
  412.  
  413.  
  414.  
  415. setSocketOptions:
  416. - setSocketOptions:(int)fd
  417.  
  418. Does nothing and returns self.  You can override this method in 
  419. subclasses to set any options that you like on the service socket's file 
  420. descriptor.  Be sure to send setSocketOptions: to super in your own 
  421. method.  If an operation fails so that you don't want the 
  422. SktSocketManager to be initialized, this method should return nil.  
  423.  
  424. See also: - initPort:logfile:fdCapacity:userClass:, fcntl(2), 
  425. setsockopt(2)
  426.  
  427.  
  428.  
  429. setTimeoutIndefinite
  430. - setTimeoutIndefinite
  431.  
  432. Causes update to wait indefinitely for input or output to process.  The 
  433. default behavior is to poll, and not wait at all.  Returns self.
  434.  
  435. See also: - isTimeoutIndefinite, 
  436. - setTimeoutSeconds:microseconds:, 
  437. - getTimeoutSeconds:microseconds:, - update, select(2)
  438.  
  439.  
  440.  
  441. setTimeoutSeconds:microseconds:
  442. - setTimeoutSeconds:(long int)secs microseconds:(long int)usecs
  443.  
  444. Records secs and usecs as the components of the timeout value used by 
  445. select() in update.  update will not wait longer than this for input or 
  446. output to process.  The default values for these components are 0 and 0; 
  447. that is, update will simply poll for input or output, not waiting at all.  
  448. Returns self.
  449.  
  450. See also: - getTimeoutSeconds:microseconds:, 
  451. - setTimeoutIndefinite, - isTimeoutIndefinite, - update, select(2)
  452.  
  453.  
  454.  
  455. signalMask
  456. - (int)signalMask
  457.  
  458. Returns the signal mask used before a call to select(), so that select() is 
  459. not affected by the signals specified in mask.
  460.  
  461. See also: - setSignalMask, - update, sigsetmask(2)
  462.  
  463.  
  464.  
  465. update
  466. - update
  467.  
  468. Performs SktSocketManager's control cycle.  First, all Sockets with 
  469. exceptions pending are closed via closeSocket:.  All remaining Sockets 
  470. are then sent a flushOutput message.  Any Sockets with input pending 
  471. are sent a getInput message.  Last, if there is a new connection pending, 
  472. then for each new connection, a new SktSocket object is created, an 
  473. object of class userClass is allocated and initialized with the new 
  474. SktSocket, and the SktSocket is added to the list of open SktSockets.  
  475. Returns self.
  476.  
  477. update makes use of the timeout specified by the last invocation of 
  478. setTimeoutSeconds:microseconds: or setTimeoutIndefinite, as well as 
  479. any mask set by setSignalMask:.  Before select() is called, the signal 
  480. mask is set, and after it returns, the previous mask is restored.  select() 
  481. uses the timeout specified by selectTimeout, or blocks indefinitely is 
  482. timeoutIndefinite is YES.
  483.  
  484. See also: - closeSocket, - flushOutput (SktSocket), - getInput 
  485. (SktSocket), - setTimeoutSeconds:microseconds:, 
  486. - getTimeoutSeconds:microseconds:, - setTimeoutIndefinite, 
  487. - isTimeoutIndefinite, - setSignalMask:, - signalMask, select(2)
  488.  
  489.  
  490.